home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / elisp-18 (.txt) < prev    next >
GNU Info File  |  1993-06-01  |  47KB  |  886 lines

  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  4. Emacs Version 19.
  5.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  6. Cambridge, MA 02139 USA
  7.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided that
  13. the entire resulting derived work is distributed under the terms of a
  14. permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that this permission notice may be stated in a
  18. translation approved by the Foundation.
  19. File: elisp,  Node: File Attributes,  Prev: Truenames,  Up: Information about Files
  20. Other Information about Files
  21. -----------------------------
  22.    This section describes the functions for getting detailed information
  23. about a file, other than its contents.  This information includes the
  24. mode bits that control access permission, the owner and group numbers,
  25. the number of names, the inode number, the size, and the times of access
  26. and modification.
  27.  - Function: file-modes FILENAME
  28.      This function returns the mode bits of FILENAME, as an integer.
  29.      The mode bits are also called the file permissions, and they
  30.      specify access control in the usual Unix fashion.  If the
  31.      low-order bit is 1, then the file is executable by all users, if
  32.      the second lowest-order bit is 1, then the file is writable by all
  33.      users, etc.
  34.      The highest value returnable is 4095 (7777 octal), meaning that
  35.      everyone has read, write, and execute permission, that the SUID bit
  36.      is set for both others and group, and that the sticky bit is set.
  37.           (file-modes "~/junk/diffs")
  38.                => 492               ; Decimal integer.
  39.           (format "%o" 492)
  40.                => 754               ; Convert to octal.
  41.           
  42.           (set-file-modes "~/junk/diffs" 438)
  43.                => nil
  44.           
  45.           (format "%o" 438)
  46.                => 666               ; Convert to octal.
  47.           
  48.           % ls -l diffs
  49.             -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
  50.  - Function: file-nlinks FILENAME
  51.      This functions returns the number of names (i.e., hard links) that
  52.      file FILENAME has.  If the file does not exist, then this function
  53.      returns `nil'.  Note that symbolic links have no effect on this
  54.      function, because they are not considered to be names of the files
  55.      they link to.
  56.           % ls -l foo*
  57.           -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
  58.           -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1
  59.           
  60.           (file-nlinks "foo")
  61.                => 2
  62.           (file-nlinks "doesnt-exist")
  63.                => nil
  64.  - Function: file-attributes FILENAME
  65.      This function returns a list of attributes of file FILENAME.  If
  66.      the specified file cannot be opened, it returns `nil'.
  67.      The elements of the list, in order, are:
  68.        0. `t' for a directory, a string for a symbolic link (the name
  69.           linked to), or `nil' for a text file.
  70.        1. The number of names the file has.  Alternate names, also
  71.           known as hard links, can be created by using the
  72.           `add-name-to-file' function (*note Changing File
  73.           Attributes::.).
  74.        2. The file's UID.
  75.        3. The file's GID.
  76.        4. The time of last access, as a list of two integers.  The
  77.           first integer has the high-order 16 bits of time, the second
  78.           has the low 16 bits.  (This is similar to the value of
  79.           `current-time'; see *Note Time of Day::.)
  80.        5. The time of last modification as a list of two integers (as
  81.           above).
  82.        6. The time of last status change as a list of two integers (as
  83.           above).
  84.        7. The size of the file in bytes.
  85.        8. The file's modes, as a string of ten letters or dashes as in
  86.           `ls -l'.
  87.        9. `t' if the file's GID would change if file were deleted and
  88.           recreated; `nil' otherwise.
  89.       10. The file's inode number.
  90.       11. The file system number of the file system that the file is
  91.           in.  This element together with the file's inode number, give
  92.           enough information to distinguish any two files on the
  93.           system--no two files can have the same values for both of
  94.           these numbers.
  95.      For example, here are the file attributes for `files.texi':
  96.           (file-attributes "files.texi")
  97.                =>  (nil
  98.                     1
  99.                     2235
  100.                     75
  101.                     (8489 20284)
  102.                     (8489 20284)
  103.                     (8489 20285)
  104.                     14906
  105.                     "-rw-rw-rw-"
  106.                     nil
  107.                     129500
  108.                     -32252)
  109.      and here is how the result is interpreted:
  110.     `nil'
  111.           is neither a directory nor a symbolic link.
  112.     `1'
  113.           has only one name (the name `files.texi' in the current
  114.           default directory).
  115.     `2235'
  116.           is owned by the user with UID 2235.
  117.     `75'
  118.           is in the group with GID 75.
  119.     `(8489 20284)'
  120.           was last accessed on Aug 19 00:09.  Unfortunately, you cannot
  121.           convert this number into a time string in Emacs.
  122.     `(8489 20284)'
  123.           was last modified on Aug 19 00:09.
  124.     `(8489 20285)'
  125.           last had its inode changed on Aug 19 00:09.
  126.     `14906'
  127.           is 14906 characters long.
  128.     `"-rw-rw-rw-"'
  129.           has a mode of read and write access for the owner, group, and
  130.           world.
  131.     `nil'
  132.           would retain the same GID if it were recreated.
  133.     `129500'
  134.           has an inode number of 129500.
  135.     `-32252'
  136.           is on file system number -32252.
  137. File: elisp,  Node: Contents of Directories,  Next: Create/Delete Dirs,  Prev: Information about Files,  Up: Files
  138. Contents of Directories
  139. =======================
  140.    A directory is a kind of file that contains other files entered under
  141. various names.  Directories are a feature of the file system.
  142.    Emacs can list the names of the files in a directory as a Lisp list,
  143. or display the names in a buffer using the `ls' shell command.  In the
  144. latter case, it can optionally display information about each file,
  145. depending on the value of switches passed to the `ls' command.
  146.  - Function: directory-files DIRECTORY &optional FULL-NAME MATCH-REGEXP
  147.           NOSORT
  148.      This function returns a list of the names of the files in the
  149.      directory DIRECTORY.  By default, the list is in alphabetical
  150.      order.
  151.      If FULL-NAME is non-`nil', the function returns the files'
  152.      absolute file names.  Otherwise, it returns just the names
  153.      relative to the specified directory.
  154.      If MATCH-REGEXP is non-`nil', this function returns only those
  155.      file names that contain that regular expression--the other file
  156.      names are discarded from the list.
  157.      If NOSORT is non-`nil', that inhibits sorting the list, so you get
  158.      the file names in no particular order.  Use this if you want the
  159.      utmost possible speed and don't care what order the files are
  160.      processed in.  If the order of processing is visible to the user,
  161.      then the user will probably be happier if you do sort the names.
  162.           (directory-files "~lewis")
  163.                => ("#foo#" "#foo.el#" "." ".."
  164.                    "dired-mods.el" "files.texi"
  165.                    "files.texi.~1~")
  166.      An error is signaled if DIRECTORY is not the name of a directory
  167.      that can be read.
  168.  - Function: file-name-all-versions FILE DIRNAME
  169.      This function returns a list of all versions of the file named
  170.      FILE in directory DIRNAME.
  171.  - Function: insert-directory FILE SWITCHES &optional WILDCARD
  172.           FULL-DIRECTORY-P
  173.      This function inserts a directory listing for directory DIR,
  174.      formatted according to SWITCHES.  It leaves point after the
  175.      inserted text.
  176.      The argument DIR may be either a directory name or a file
  177.      specification including wildcard characters.  If WILDCARD is
  178.      non-`nil', that means treat FILE as a file specification with
  179.      wildcards.
  180.      If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
  181.      and switches do not contain `d', so that a full listing is
  182.      expected.
  183.      This function works by running a directory listing program whose
  184.      name is in the variable `insert-directory-program'.  If WILDCARD is
  185.      non-`nil', it also runs the shell specified by `shell-file-name',
  186.      to expand the wildcards.
  187.  - Variable: insert-directory-program
  188.      This variable's value is the program to run to generate a
  189.      directory listing for the function `insert-directory'.
  190. File: elisp,  Node: Create/Delete Dirs,  Next: Changing File Attributes,  Prev: Contents of Directories,  Up: Files
  191. Creating and Deleting Directories
  192. =================================
  193.  - Function: make-directory DIRNAME
  194.      This function creates a directory named DIRNAME.
  195.  - Function: delete-directory DIRNAME
  196.      This function deletes the directory named DIRNAME.  The function
  197.      `delete-file' does not work for files that are directories; you
  198.      must use `delete-directory' in that case.
  199. File: elisp,  Node: Changing File Attributes,  Next: File Names,  Prev: Create/Delete Dirs,  Up: Files
  200. Changing File Names and Attributes
  201. ==================================
  202.    The functions in this section rename, copy, delete, link, and set the
  203. modes of files.
  204.    In the functions that have an argument NEWNAME, if a file by the
  205. name of NEWNAME already exists, the actions taken depend on the value
  206. of the argument OK-IF-ALREADY-EXISTS:
  207.    * A `file-already-exists' error is signaled if OK-IF-ALREADY-EXISTS
  208.      is `nil'.
  209.    * Confirmation is requested if OK-IF-ALREADY-EXISTS is a number.
  210.    * No confirmation is requested if OK-IF-ALREADY-EXISTS is any other
  211.      value, in which case the old file is removed.
  212.  - Function: add-name-to-file OLDNAME NEWNAME &optional
  213.           OK-IF-ALREADY-EXISTS
  214.      This function gives the file named OLDNAME the additional name
  215.      NEWNAME.  This means that NEWNAME becomes a new "hard link" to
  216.      OLDNAME.
  217.      In the first part of the following example, we list two files,
  218.      `foo' and `foo3'.
  219.           % ls -l fo*
  220.           -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
  221.           -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
  222.      Then we evaluate the form `(add-name-to-file "~/lewis/foo"
  223.      "~/lewis/foo2")'.  Again we list the files.  This shows two names,
  224.      `foo' and `foo2'.
  225.           (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
  226.                => nil
  227.           
  228.           % ls -l fo*
  229.           -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
  230.           -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
  231.           -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
  232.      Finally, we evaluate the following:
  233.           (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
  234.      and list the files again.  Now there are three names for one file:
  235.      `foo', `foo2', and `foo3'.  The old contents of `foo3' are lost.
  236.           (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
  237.                => nil
  238.           
  239.           % ls -l fo*
  240.           -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
  241.           -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
  242.           -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
  243.      This function is meaningless on VMS, where multiple names for one
  244.      file are not allowed.
  245.      See also `file-nlinks' in *Note File Attributes::.
  246.  - Command: rename-file FILENAME NEWNAME &optional OK-IF-ALREADY-EXISTS
  247.      This command renames the file FILENAME as NEWNAME.
  248.      If FILENAME has additional names aside from FILENAME, it continues
  249.      to have those names.  In fact, adding the name NEWNAME with
  250.      `add-name-to-file' and then deleting FILENAME has the same effect
  251.      as renaming, aside from momentary intermediate states.
  252.      In an interactive call, this function prompts for FILENAME and
  253.      NEWNAME in the minibuffer; also, it requests confirmation if
  254.      NEWNAME already exists.
  255.  - Command: copy-file OLDNAME NEWNAME &optional OK-IF-EXISTS TIME
  256.      This command copies the file OLDNAME to NEWNAME.  An error is
  257.      signaled if OLDNAME does not exist.
  258.      If TIME is non-`nil', then this functions gives the new file the
  259.      same last-modified time that the old one has.  (This works on only
  260.      some operating systems.)
  261.      In an interactive call, this function prompts for FILENAME and
  262.      NEWNAME in the minibuffer; also, it requests confirmation if
  263.      NEWNAME already exists.
  264.  - Command: delete-file FILENAME
  265.      This command deletes the file FILENAME, like the shell command `rm
  266.      FILENAME'.  If the file has multiple names, it continues to exist
  267.      under the other names.
  268.      A suitable kind of `file-error' error is signaled if the file does
  269.      not exist, or is not deletable.  (In Unix, a file is deletable if
  270.      its directory is writable.)
  271.      See also `delete-directory' in *Note Create/Delete Dirs::.
  272.  - Command: make-symbolic-link FILENAME NEWNAME &optional OK-IF-EXISTS
  273.      This command makes a symbolic link to FILENAME, named NEWNAME.
  274.      This is like the shell command `ln -s FILENAME NEWNAME'.
  275.      In an interactive call, FILENAME and NEWNAME are read in the
  276.      minibuffer, and OK-IF-EXISTS is set to the numeric prefix argument.
  277.  - Function: define-logical-name VARNAME STRING
  278.      This function defines the logical name NAME to have the value
  279.      STRING.  It is available only on VMS.
  280.  - Function: set-file-modes FILENAME MODE
  281.      This function sets mode bits of FILENAME to MODE (which must be an
  282.      integer).  Only the 12 low bits of MODE are used.
  283.  - Function: set-default-file-modes MODE
  284.      This function sets the default file protection for new files
  285.      created by Emacs and its subprocesses.  Every file created with
  286.      Emacs initially has this protection.  On Unix, the default
  287.      protection is the bitwise complement of the "umask" value.
  288.      The argument MODE must be an integer.  Only the 9 low bits of MODE
  289.      are used.
  290.      Saving a modified version of an existing file does not count as
  291.      creating the file; it does not change the file's mode, and does
  292.      not use the default file protection.
  293.  - Function: default-file-modes
  294.      This function returns the current default protection value.
  295. File: elisp,  Node: File Names,  Next: Magic File Names,  Prev: Changing File Attributes,  Up: Files
  296. File Names
  297. ==========
  298.    Files are generally referred to by their names, in Emacs as
  299. elsewhere.  File names in Emacs are represented as strings.  The
  300. functions that operate on a file all expect a file name argument.
  301.    In addition to operating on files themselves, Emacs Lisp programs
  302. often need to operate on the names; i.e., to take them apart and to use
  303. part of a name to construct related file names.  This section describes
  304. how to manipulate file names.
  305.    The functions in this section do not actually access files, so they
  306. can operate on file names that do not refer to an existing file or
  307. directory.
  308.    On VMS, all these functions understand both VMS file name syntax and
  309. Unix syntax.  This is so that all the standard Lisp libraries can
  310. specify file names in Unix syntax and work properly on VMS without
  311. change.
  312. * Menu:
  313. * File Name Components::  The directory part of a file name, and the rest.
  314. * Directory Names::       A directory's name as a directory
  315.                             is different from its name as a file.
  316. * Relative File Names::   Some file names are relative to a current directory.
  317. * File Name Expansion::   Converting relative file names to absolute ones.
  318. * Unique File Names::     Generating names for temporary files.
  319. * File Name Completion::  Finding the completions for a given file name.
  320. File: elisp,  Node: File Name Components,  Next: Directory Names,  Up: File Names
  321. File Name Components
  322. --------------------
  323.    The operating system groups files into directories.  To specify a
  324. file, you must specify the directory, and the file's name in that
  325. directory.  Therefore, a file name in Emacs is considered to have two
  326. main parts: the "directory name" part, and the "nondirectory" part (or
  327. "file name within the directory").  Either part may be empty.
  328. Concatenating these two parts reproduces the original file name.
  329.    On Unix, the directory part is everything up to and including the
  330. last slash; the nondirectory part is the rest.  The rules in VMS syntax
  331. are complicated.
  332.    For some purposes, the nondirectory part is further subdivided into
  333. the name proper and the "version number".  On Unix, only backup files
  334. have version numbers in their names; on VMS, every file has a version
  335. number, but most of the time the file name actually used in Emacs omits
  336. the version number.  Version numbers are found mostly in directory
  337. lists.
  338.  - Function: file-name-directory FILENAME
  339.      This function returns the directory part of FILENAME (or `nil' if
  340.      FILENAME does not include a directory part).  On Unix, the
  341.      function returns a string ending in a slash.  On VMS, it returns a
  342.      string ending in one of the three characters `:', `]', or `>'.
  343.           (file-name-directory "lewis/foo")  ; Unix example
  344.                => "lewis/"
  345.           (file-name-directory "foo")        ; Unix example
  346.                => nil
  347.           (file-name-directory "[X]FOO.TMP") ; VMS example
  348.                => "[X]"
  349.  - Function: file-name-nondirectory FILENAME
  350.      This function returns the nondirectory part of FILENAME.
  351.           (file-name-nondirectory "lewis/foo")
  352.                => "foo"
  353.           (file-name-nondirectory "foo")
  354.                => "foo"
  355.           ;; The following example is accurate only on VMS.
  356.           (file-name-nondirectory "[X]FOO.TMP")
  357.                => "FOO.TMP"
  358.  - Function: file-name-sans-versions FILENAME
  359.      This function returns FILENAME without any file version numbers,
  360.      backup version numbers, or trailing tildes.
  361.           (file-name-sans-versions "~rms/foo.~1~")
  362.                => "~rms/foo"
  363.           (file-name-sans-versions "~rms/foo~")
  364.                => "~rms/foo"
  365.           (file-name-sans-versions "~rms/foo")
  366.                => "~rms/foo"
  367.           ;; The following example applies to VMS only.
  368.           (file-name-sans-versions "foo;23")
  369.                => "foo"
  370. File: elisp,  Node: Directory Names,  Next: Relative File Names,  Prev: File Name Components,  Up: File Names
  371. Directory Names
  372. ---------------
  373.    A "directory name" is the name of a directory.  A directory is a
  374. kind of file, and it has a file name, which is related to the directory
  375. name but not identical to it.  (This is not quite the same as the usual
  376. Unix terminology.)  These two different names for the same entity are
  377. related by a syntactic transformation.  On Unix, this is simple: a
  378. directory name ends in a slash, whereas the directory's name as a file
  379. lacks that slash.  On VMS, the relationship is more complicated.
  380.    The difference between a directory name and its name as a file is
  381. subtle but crucial.  When an Emacs variable or function argument is
  382. described as being a directory name, a file name of a directory is not
  383. acceptable.
  384.    These two functions take a single argument, FILENAME, which must be
  385. a string.  Environment variable substitutions such as `$HOME', and the
  386. symbols `~', and `..', are *not* expanded.  Use `expand-file-name' or
  387. `substitute-in-file-name' for that (*note File Name Expansion::.).
  388.  - Function: file-name-as-directory FILENAME
  389.      This function returns a string representing FILENAME in a form
  390.      that the operating system will interpret as the name of a
  391.      directory.  In Unix, this means that a slash is appended to the
  392.      string.  On VMS, the function converts a string of the form
  393.      `[X]Y.DIR.1' to the form `[X.Y]'.
  394.           (file-name-as-directory "~rms/lewis")
  395.                => "~rms/lewis/"
  396.  - Function: directory-file-name DIRNAME
  397.      This function returns a string representing DIRNAME in a form that
  398.      the operating system will interpret as the name of a file.  On
  399.      Unix, this means removing a final slash from the string.  On VMS,
  400.      the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
  401.           (directory-file-name "~lewis/")
  402.                => "~lewis"
  403.    Directory name abbreviations are useful for directories that are
  404. normally accessed through symbolic links.  Sometimes the users recognize
  405. primarily the link's name as "the name" of the directory, and find it
  406. annoying to see the directory's "real" name.  If you define the link
  407. name as an abbreviation for the "real" name, Emacs shows users the
  408. abbreviation instead.
  409.    If you wish to convert a directory name to its abbreviation, use this
  410. function:
  411.  - Function: abbreviate-file-name DIRNAME
  412.      This function applies abbreviations from `directory-abbrev-alist'
  413.      to its argument, and substitutes `~' for the user's home directory.
  414.  - Variable: directory-abbrev-alist
  415.      The variable `directory-abbrev-alist' contains an alist of
  416.      abbreviations to use for file directories.  Each element has the
  417.      form `(FROM . TO)', and says to replace FROM with TO when it
  418.      appears in a directory name.  The FROM string is actually a
  419.      regular expression; it should always start with `^'.  The function
  420.      `abbreviate-file-name' performs these substitutions.
  421.      You can set this variable in `site-init.el' to describe the
  422.      abbreviations appropriate for your site.
  423.      Here's an example, from a system on which file system `/home/fsf'
  424.      and so on are normally accessed through symbolic links named `/fsf'
  425.      and so on.
  426.           (("^/home/fsf" . "/fsf")
  427.            ("^/home/gp" . "/gp")
  428.            ("^/home/gd" . "/gd"))
  429. File: elisp,  Node: Relative File Names,  Next: File Name Expansion,  Prev: Directory Names,  Up: File Names
  430. Absolute and Relative File Names
  431. --------------------------------
  432.    All the directories in the file system form a tree starting at the
  433. root directory.  A file name can specify all the directory names
  434. starting from the root of the tree; then it is called an "absolute"
  435. file name.  Or it can specify the position of the file in the tree
  436. relative to a default directory; then it is called an "relative" file
  437. name.  On Unix, an absolute file name starts with a slash or a tilde
  438. (`~'), and a relative one does not.  The rules on VMS are complicated.
  439.  - Function: file-name-absolute-p FILENAME
  440.      This function returns `t' if file FILENAME is an absolute file
  441.      name, `nil' otherwise.  On VMS, this function understands both
  442.      Unix syntax and VMS syntax.
  443.           (file-name-absolute-p "~rms/foo")
  444.                => t
  445.           (file-name-absolute-p "rms/foo")
  446.                => nil
  447.           (file-name-absolute-p "/user/rms/foo")
  448.                => t
  449. File: elisp,  Node: File Name Expansion,  Next: Unique File Names,  Prev: Relative File Names,  Up: File Names
  450. Functions that Expand Filenames
  451. -------------------------------
  452.    "Expansion" of a file name means converting a relative file name to
  453. an absolute one.  Since this is done relative to a default directory,
  454. you must specify the default directory name as well as the file name to
  455. be expanded.  Expansion also simplifies file names by eliminating
  456. redundancies such as `./' and `NAME/../'.
  457.  - Function: expand-file-name FILENAME &optional DIRECTORY
  458.      This function converts FILENAME to an absolute file name.  If
  459.      DIRECTORY is supplied, it is the directory to start with if
  460.      FILENAME is relative.  (The value of DIRECTORY should itself be an
  461.      absolute, expanded file name; it should not start with `~'.)
  462.      Otherwise, the current buffer's value of `default-directory' is
  463.      used.  For example:
  464.           (expand-file-name "foo")
  465.                => "/xcssun/users/rms/lewis/foo"
  466.           (expand-file-name "../foo")
  467.                => "/xcssun/users/rms/foo"
  468.           (expand-file-name "foo" "/usr/spool/")
  469.                => "/usr/spool/foo"
  470.           (expand-file-name "$HOME/foo")
  471.                => "/xcssun/users/rms/lewis/$HOME/foo"
  472.      Filenames containing `.' or `..' are simplified to their canonical
  473.      form:
  474.           (expand-file-name "bar/../foo")
  475.                => "/xcssun/users/rms/lewis/foo"
  476.      `~/' is expanded into the user's home directory.  A `/' or `~'
  477.      following a `/' is taken to be the start of an absolute file name
  478.      that overrides what precedes it, so everything before that `/' or
  479.      `~' is deleted.  For example:
  480.           (expand-file-name
  481.            "/a1/gnu//usr/local/lib/emacs/etc/MACHINES")
  482.                => "/usr/local/lib/emacs/etc/MACHINES"
  483.           (expand-file-name "/a1/gnu/~/foo")
  484.                => "/xcssun/users/rms/foo"
  485.      In both cases, `/a1/gnu/' is discarded because an absolute file
  486.      name follows it.
  487.      Note that `expand-file-name' does *not* expand environment
  488.      variables; that is done only by `substitute-in-file-name'.
  489.  - Function: file-relative-name FILENAME DIRECTORY
  490.      This function does the inverse of expansion--it tries to return a
  491.      relative name which is equivalent to FILENAME when interpreted
  492.      relative to DIRECTORY.  (If such a relative name would be longer
  493.      than the absolute name, it returns the absolute name instead.)
  494.           (file-relative-name "/foo/bar" "/foo/")
  495.                => "bar")
  496.           (file-relative-name "/foo/bar" "/hack/")
  497.                => "/foo/bar")
  498.  - Variable: default-directory
  499.      The value of this buffer-local variable is the default directory
  500.      for the current buffer.  It is local in every buffer.
  501.      `expand-file-name' uses the default directory when its second
  502.      argument is `nil'.
  503.      On Unix systems, the value is always a string ending with a slash.
  504.           default-directory
  505.                => "/user/lewis/manual/"
  506.  - Function: substitute-in-file-name FILENAME
  507.      This function replaces environment variables names in FILENAME
  508.      with the values to which they are set by the operating system.
  509.      Following standard Unix shell syntax, `$' is the prefix to
  510.      substitute an environment variable value.
  511.      The environment variable name is the series of alphanumeric
  512.      characters (including underscores) that follow the `$'.  If the
  513.      character following the `$' is a `{', then the variable name is
  514.      everything up to the matching `}'.
  515.      Here we assume that the environment variable `HOME', which holds
  516.      the user's home directory name, has the value `/xcssun/users/rms'.
  517.           (substitute-in-file-name "$HOME/foo")
  518.                => "/xcssun/users/rms/foo"
  519.      If a `~' or a `/' appears following a `/', after substitution,
  520.      everything before the following `/' is discarded:
  521.           (substitute-in-file-name "bar/~/foo")
  522.                => "~/foo"
  523.           (substitute-in-file-name "/usr/local/$HOME/foo")
  524.                => "/xcssun/users/rms/foo"
  525.      On VMS, `$' substitution is not done, so this function does nothing
  526.      on VMS except discard superfluous initial components as shown
  527.      above.
  528. File: elisp,  Node: Unique File Names,  Next: File Name Completion,  Prev: File Name Expansion,  Up: File Names
  529. Generating Unique File Names
  530. ----------------------------
  531.    Some programs need to write temporary files.  Here is the usual way
  532. to construct a name for such a file:
  533.      (make-temp-name (concat "/tmp/" NAME-OF-APPLICATION))
  534. Here we use the directory `/tmp/' because that is the standard place on
  535. Unix for temporary files.  The job of `make-temp-name' is to prevent
  536. two different users or two different jobs from trying to use the same
  537. name.
  538.  - Function: make-temp-name STRING
  539.      This function generates string that can be used as a unique name.
  540.      The name starts with the prefix STRING, and ends with a number that
  541.      is different in each Emacs job.
  542.           (make-temp-name "/tmp/foo")
  543.                => "/tmp/foo021304"
  544.      To prevent conflicts among different application libraries run in
  545.      the same Emacs, each application should have its own STRING.  The
  546.      number added to the end of the name distinguishes between the same
  547.      application running in different Emacs jobs.
  548. File: elisp,  Node: File Name Completion,  Prev: Unique File Names,  Up: File Names
  549. File Name Completion
  550. --------------------
  551.    This section describes low-level subroutines for completing a file
  552. name.  For other completion functions, see *Note Completion::.
  553.  - Function: file-name-all-completions PARTIAL-FILENAME DIRECTORY
  554.      This function returns a list of all possible completions for a file
  555.      whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
  556.      The order of the completions is the order of the files in the
  557.      directory, which is unpredictable and conveys no useful
  558.      information.
  559.      The argument PARTIAL-FILENAME must be a file name containing no
  560.      directory part and no slash.  The current buffer's default
  561.      directory is prepended to DIRECTORY, if DIRECTORY is not an
  562.      absolute file name.
  563.      In the following example, suppose that the current default
  564.      directory, `~rms/lewis', has five files whose names begin with `f':
  565.      `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
  566.           (file-name-all-completions "f" "")
  567.                => ("foo" "file~" "file.c.~2~"
  568.                           "file.c.~1~" "file.c")
  569.           
  570.           (file-name-all-completions "fo" "")
  571.                => ("foo")
  572.  - Function: file-name-completion FILENAME DIRECTORY
  573.      This function completes the file name FILENAME in directory
  574.      DIRECTORY.  It returns the longest prefix common to all file names
  575.      in directory DIRECTORY that start with FILENAME.
  576.      If only one match exists and FILENAME matches it exactly, the
  577.      function returns `t'.  The function returns `nil' if directory
  578.      DIRECTORY contains no name starting with FILENAME.
  579.      In the following example, suppose that the current default
  580.      directory has five files whose names begin with `f': `foo',
  581.      `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
  582.           (file-name-completion "fi" "")
  583.                => "file"
  584.           
  585.           (file-name-completion "file.c.~1" "")
  586.                => "file.c.~1~"
  587.           
  588.           (file-name-completion "file.c.~1~" "")
  589.                => t
  590.           
  591.           (file-name-completion "file.c.~3" "")
  592.                => nil
  593.  - User Option: completion-ignored-extensions
  594.      `file-name-completion' usually ignores file names that end in any
  595.      string in this list.  It does not ignore them when all the possible
  596.      completions end in one of these suffixes or when a buffer showing
  597.      all possible completions is displayed.
  598.      A typical value might look like this:
  599.           completion-ignored-extensions
  600.                => (".o" ".elc" "~" ".dvi")
  601. File: elisp,  Node: Magic File Names,  Prev: File Names,  Up: Files
  602. Making Certain File Names "Magic"
  603. =================================
  604.    You can implement special handling for certain file names.  This is
  605. called making those names "magic".  You must supply a regular
  606. expression to define the class of names (all those which match the
  607. regular expression), plus a handler that implements all the primitive
  608. Emacs file operations for file names that do match.
  609.    The value of `file-name-handler-alist' is a list of handlers,
  610. together with regular expressions that decide when to apply each
  611. handler.  Each element has this form:
  612.      (REGEXP . HANDLER)
  613. All the Emacs primitives for file access and file name transformation
  614. check the given file name against `file-name-handler-alist'.  If the
  615. file name matches REGEXP, the primitives handle that file by calling
  616. HANDLER.
  617.    The first argument given to HANDLER is the name of the primitive;
  618. the remaining arguments are the arguments that were passed to that
  619. operation.  (The first of these arguments is typically the file name
  620. itself.)  For example, if you do this:
  621.      (file-exists-p FILENAME)
  622. and FILENAME has handler HANDLER, then HANDLER is called like this:
  623.      (funcall HANDLER 'file-exists-p FILENAME)
  624.    Here are the operations that you can handle for a magic file name:
  625. `add-name-to-file', `copy-file', `delete-directory',
  626. `delete-file', `directory-file-name', `directory-files',
  627. `dired-compress-file', `dired-uncache',
  628. `expand-file-name', `file-accessible-directory-p',
  629. `file-attributes', `file-directory-p',
  630. `file-executable-p', `file-exists-p', `file-local-copy',
  631. `file-modes', `file-name-all-completions',
  632. `file-name-as-directory', `file-name-completion',
  633. `file-name-directory', `file-name-nondirectory',
  634. `file-name-sans-versions', `file-newer-than-file-p',
  635. `file-readable-p', `file-symlink-p', `file-writable-p',
  636. `insert-directory', `insert-file-contents',
  637. `make-directory', `make-symbolic-link', `rename-file',
  638. `set-file-modes', `set-visited-file-modtime',
  639. `unhandled-file-name-directory',
  640. `verify-visited-file-modtime', `write-region'.
  641.    The handler function must handle all of the above operations, and
  642. possibly others to be added in the future.  Therefore, it should always
  643. reinvoke the ordinary Lisp primitive when it receives an operation it
  644. does not recognize.  Here's one way to do this:
  645.      (defun my-file-handler (operation &rest args)
  646.        ;; First check for the specific operations
  647.        ;; that we have special handling for.
  648.        (cond ((eq operation 'insert-file-contents) ...)
  649.              ((eq operation 'write-region) ...)
  650.              ...
  651.              ;; Handle any operation we don't know about.
  652.              (t (let (file-name-handler-alist)
  653.                   (apply operation args)))))
  654.  - Function: find-file-name-handler FILE
  655.      This function returns the handler function for file name FILE, or
  656.      `nil' if there is none.
  657.  - Function: file-local-copy FILENAME
  658.      This function copies file FILENAME to the local site, if it isn't
  659.      there already.  If FILENAME specifies a "magic" file name which
  660.      programs outside Emacs cannot directly read or write, this copies
  661.      the contents to an ordinary file and returns that file's name.
  662.      If FILENAME is an ordinary file name, not magic, then this function
  663.      does nothing and returns `nil'.
  664.  - Function: unhandled-file-name-directory FILENAME
  665.      This function returns the name of a directory that is not magic.
  666.      It uses the directory part of FILENAME if that is not magic.
  667.      Otherwise, it asks the handler what to do.
  668.      This is used for running a subprocess; any subprocess must have a
  669.      non-magic directory to serve as its current directory.
  670. File: elisp,  Node: Backups and Auto-Saving,  Next: Buffers,  Prev: Files,  Up: Top
  671. Backups and Auto-Saving
  672. ***********************
  673.    Backup files and auto-save files are two methods by which Emacs tries
  674. to protect the user from the consequences of crashes or of the user's
  675. own errors.  Auto-saving preserves the text from earlier in the current
  676. editing session; backup files preserve file contents prior to the
  677. current session.
  678. * Menu:
  679. * Backup Files::   How backup files are made; how their names are chosen.
  680. * Auto-Saving::    How auto-save files are made; how their names are chosen.
  681. * Reverting::      `revert-buffer', and how to customize what it does.
  682. File: elisp,  Node: Backup Files,  Next: Auto-Saving,  Prev: Backups and Auto-Saving,  Up: Backups and Auto-Saving
  683. Backup Files
  684. ============
  685.    A "backup file" is a copy of the old contents of a file you are
  686. editing.  Emacs makes a backup file the first time you save a buffer
  687. into its visited file.  Normally, this means that the backup file
  688. contains the contents of the file as it was before the current editing
  689. session.  The contents of the backup file normally remain unchanged once
  690. it exists.
  691.    Backups are usually made by renaming the visited file to a new name.
  692. Optionally, you can specify that backup files should be made by copying
  693. the visited file.  This choice makes a difference for files with
  694. multiple names; it also can affect whether the edited file remains owned
  695. by the original owner or becomes owned by the user editing it.
  696.    By default, Emacs makes a single backup file for each file edited.
  697. You can alternatively request numbered backups; then each new backup
  698. file gets a new name.  You can delete old numbered backups when you
  699. don't want them any more, or Emacs can delete them automatically.
  700. * Menu:
  701. * Making Backups::     How Emacs makes backup files, and when.
  702. * Rename or Copy::     Two alternatives: renaming the old file or copying it.
  703. * Numbered Backups::   Keeping multiple backups for each source file.
  704. * Backup Names::       How backup file names are computed; customization.
  705. File: elisp,  Node: Making Backups,  Next: Rename or Copy,  Prev: Backup Files,  Up: Backup Files
  706. Making Backup Files
  707. -------------------
  708.  - Function: backup-buffer
  709.      This function makes a backup of the file visited by the current
  710.      buffer, if appropriate.  It is called by `save-buffer' before
  711.      saving the buffer the first time.
  712.  - Variable: buffer-backed-up
  713.      This buffer-local variable indicates whether this buffer's file has
  714.      been backed up on account of this buffer.  If it is non-`nil', then
  715.      the backup file has been written.  Otherwise, the file should be
  716.      backed up when it is next saved (if backup files are enabled).
  717.      This is a permanent local; `kill-local-variables' does not alter
  718.      it.
  719.  - User Option: make-backup-files
  720.      This variable determines whether or not to make backup files.  If
  721.      it is non-`nil', then Emacs creates a backup of each file when it
  722.      is saved for the first time.
  723.      The following example shows how to change the `make-backup-files'
  724.      variable only in the `RMAIL' buffer and not elsewhere.  Setting it
  725.      `nil' stops Emacs from making backups of the `RMAIL' file, which
  726.      may save disk space.  (You would put this code in your `.emacs'
  727.      file.)
  728.           (add-hook 'rmail-mode-hook
  729.                     (function (lambda ()
  730.                                 (make-local-variable
  731.                                  'make-backup-files)
  732.                                 (setq make-backup-files nil))))
  733.  - Variable: backup-enable-predicate
  734.      This variable's value is a function to be called on certain
  735.      occasions to decide whether a there should be backup files for
  736.      file name FILENAME.  If it returns `nil', backups are disabled.
  737.      Otherwise, backups are enabled (if `make-backup-files' is true).
  738. File: elisp,  Node: Rename or Copy,  Next: Numbered Backups,  Prev: Making Backups,  Up: Backup Files
  739. Backup by Renaming or by Copying?
  740. ---------------------------------
  741.    There are two ways that Emacs can make a backup file:
  742.    * Emacs can rename the original file so that it becomes a backup
  743.      file, and then write the buffer being saved into a new file.
  744.      After this procedure, any other names (i.e., hard links) of the
  745.      original file now refer to the backup file.  The new file is owned
  746.      by the user doing the editing, and its group is the default for
  747.      new files written by the user in that directory.
  748.    * Emacs can copy the original file into a backup file, and then
  749.      overwrite the original file with new contents.  After this
  750.      procedure, any other names (i.e., hard links) of the original file
  751.      still refer to the current version of the file.  The file's owner
  752.      and group will be unchanged.
  753.    The first method, renaming, is the default.
  754.    The variable `backup-by-copying', if non-`nil', says to use the
  755. second method, which is to copy the original file and overwrite it with
  756. the new buffer contents.  The variable `file-precious-flag', if
  757. non-`nil', also has this effect (as a sideline of its main
  758. significance).  *Note Saving Buffers::.
  759.    The following two variables, when non-`nil', cause the second method
  760. to be used in certain special cases.  They have no effect on the
  761. treatment of files that don't fall into the special cases.
  762.  - Variable: backup-by-copying
  763.      This variable controls whether to make backup files by copying.
  764.      If it is non-`nil', then Emacs always copies the current contents
  765.      of the file into the backup file before writing the buffer to be
  766.      saved to the file.  (In many circumstances, this has the same
  767.      effect as `file-precious-flag'.)
  768.  - Variable: backup-by-copying-when-linked
  769.      This variable controls whether to make backups by copying for files
  770.      with multiple names (hard links).  If it is non-`nil', then Emacs
  771.      uses copying to create backups for those files.
  772.      This variable is significant only if `backup-by-copying' is `nil',
  773.      since copying is always used when that variable is non-`nil'.
  774.  - Variable: backup-by-copying-when-mismatch
  775.      This variable controls whether to make backups by copying in cases
  776.      where renaming would change either the owner or the group of the
  777.      file.  If it is non-`nil' then Emacs creates backups by copying in
  778.      such cases.
  779.      The value has no effect when renaming would not alter the owner or
  780.      group of the file; that is, for files which are owned by the user
  781.      and whose group matches the default for a new file created there
  782.      by the user.
  783.      This variable is significant only if `backup-by-copying' is `nil',
  784.      since copying is always used when that variable is non-`nil'.
  785. File: elisp,  Node: Numbered Backups,  Next: Backup Names,  Prev: Rename or Copy,  Up: Backup Files
  786. Making and Deleting Numbered Backup Files
  787. -----------------------------------------
  788.    If a file's name is `foo', the names of its numbered backup versions
  789. are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
  790. `foo.~3~', ..., `foo.~259~', and so on.
  791.  - User Option: version-control
  792.      This variable controls whether to make a single non-numbered backup
  793.      file or multiple numbered backups.
  794.     `nil'
  795.           Make numbered backups if the visited file already has
  796.           numbered backups; otherwise, do not.
  797.     `never'
  798.           Do not make numbered backups.
  799.     ANYTHING ELSE
  800.           Do make numbered backups.
  801.    The use of numbered backups ultimately leads to a large number of
  802. backup versions, which must then be deleted.  Emacs can do this
  803. automatically.
  804.  - User Option: kept-new-versions
  805.      The value of this variable is the number of oldest versions to keep
  806.      when a new numbered backup is made.  The newly made backup is
  807.      included in the count.  The default value is 2.
  808.  - User Option: kept-old-versions
  809.      The value of this variable is the number of oldest versions to keep
  810.      when a new numbered backup is made.  The default value is 2.
  811.  - User Option: dired-kept-versions
  812.      This variable plays a role in Dired's `dired-clean-directory'
  813.      (`.') command like that played by `kept-old-versions' when a
  814.      backup file is made.  The default value is 2.
  815.    If there are backups numbered 1, 2, 3, 5, and 7, and both of these
  816. variables have the value 2, then the backups numbered 1 and 2 are kept
  817. as old versions and those numbered 5 and 7 are kept as new versions;
  818. backup version 3 is deleted.  The function `find-backup-file-name'
  819. (*note Backup Names::.) is responsible for determining which backup
  820. versions to delete, but does not delete them itself.
  821.  - User Option: trim-versions-without-asking
  822.      If this variable is non-`nil', then saving a file deletes excess
  823.      backup versions silently.  Otherwise, it asks the user whether to
  824.      delete them.
  825. File: elisp,  Node: Backup Names,  Prev: Numbered Backups,  Up: Backup Files
  826. Naming Backup Files
  827. -------------------
  828.    The functions in this section are documented mainly because you can
  829. customize the naming conventions for backup files by redefining them.
  830. If you change one, you probably need to change the rest.
  831.  - Function: backup-file-name-p FILENAME
  832.      This function returns a non-`nil' value if FILENAME is a possible
  833.      name for a backup file.  A file with the name FILENAME need not
  834.      exist; the function just checks the name.
  835.           (backup-file-name-p "foo")
  836.                => nil
  837.           (backup-file-name-p "foo~")
  838.                => 3
  839.      The standard definition of this function is as follows:
  840.           (defun backup-file-name-p (file)
  841.             "Return non-nil if FILE is a backup file \
  842.           name (numeric or not)..."
  843.             (string-match "~$" file))
  844.      Thus, the function returns a non-`nil' value if the file name ends
  845.      with a `~'.  (We use a backslash to split the documentation
  846.      string's first line into two lines in the text, but produce just
  847.      one line in the string itself.)
  848.      This simple expression is placed in a separate function to make it
  849.      easy to redefine for customization.
  850.  - Function: make-backup-file-name FILENAME
  851.      This function returns a string which is the name to use for a
  852.      non-numbered backup file for file FILENAME.  On Unix, this is just
  853.      FILENAME with a tilde appended.
  854.      The standard definition of this function is as follows:
  855.           (defun make-backup-file-name (file)
  856.             "Create the non-numeric backup file name for FILE..."
  857.             (concat file "~"))
  858.      You can change the backup file naming convention by redefining this
  859.      function.  In the following example, `make-backup-file-name' is
  860.      redefined to prepend a `.' as well as to append a tilde.
  861.           (defun make-backup-file-name (filename)
  862.             (concat "." filename "~"))
  863.           
  864.           (make-backup-file-name "backups.texi")
  865.                => ".backups.texi~"
  866.  - Function: find-backup-file-name FILENAME
  867.      This function computes the file name for a new backup file for
  868.      FILENAME.  It may also propose certain existing backup files for
  869.      deletion.  `find-backup-file-name' returns a list whose CAR is the
  870.      name for the new backup file and whose CDR is a list of backup
  871.      files whose deletion is proposed.
  872.      Two variables, `kept-old-versions' and `kept-new-versions',
  873.      determine which old backup versions should be kept (by excluding
  874.      them from the list of backup files ripe for deletion).  *Note
  875.      Numbered Backups::.
  876.      In this example, the value says that `~rms/foo.~5~' is the name to
  877.      use for the new backup file, and `~rms/foo.~3~' is an "excess"
  878.      version that the caller should consider deleting now.
  879.           (find-backup-file-name "~rms/foo")
  880.                => ("~rms/foo.~5~" "~rms/foo.~3~")
  881.  - Function: file-newest-backup FILENAME
  882.      This function returns the name of the most recent backup file for
  883.      FILENAME, or `nil' that file has no backup files.
  884.      Some file comparison commands use this function in order to compare
  885.      a file by default with its most recent backup.
  886.